//
//  MessageAddressee.h
//  MailDelivery
//
//  Created by Dante Palacios on 9/29/09.
//  Copyright 2009 Dante Palacios. All rights reserved.
//

/*!
 @header MessageAddressee.h
 @abstract The methods listed here may disappear or change their names without prior notice. For more information, contact palacios.dante\@gmail.com.
 */

#import <Foundation/Foundation.h>

/*!
 @protocol MessageAddressee
 @abstract ...
 */

@protocol MessageAddressee <NSObject>

@required;

/*!
 @property address
 @abstract The email address. Cannot be nil.
 @textblock
 E.g jdoe@example.com .
 @/textblock
 */

@property (readonly, retain) NSString *address;

/*!
 @property fullEmailAddress
 @abstract The full email address. 
 @textblock
 E.g "John Doe <jdoe@example.com>"
 @/textblock
 */

@property (readonly) NSString *fullEmailAddress;

/*!
 @property description
 @abstract From the NSObject protocol, must returns the full email address @link fullEmailAddress fullEmailAddress @/link.
 */

@property (readonly) NSString *description;

@optional;

/*!
 @property displayName
 @abstract The display name. Can be nil. 
 @textblock 
 E.g. with "John Doe <jdoe@example.com>" as the full email address, display name would be "John Doe".
 @/textblock
 */

@property (readonly, retain) NSString *displayName;

/*!
 @property userName
 @abstract The user name. Can be nil.
 @textblock
 E.g with "John Doe <jdoe@example.com>" as the full email address, user name most of the times would be "jdoe".
 @/textblock
 */

@property (readonly, retain) NSString *userName;

/*!
 @property domain
 @abstract The domain of the address. 
 @textblock 
 E.g with "John Doe <jdoe@example.com>" as the full email address, domain most of the times would be "example.com".
 @/textblock
 
 */

@property (readonly, retain) NSString *domain;

/*!
 @property hostName
 @abstract The host name of the address. 
 @textblock
 E.g with "John Doe <jdoe@example.com>" as the full email address, host name most of the times would be "smtp.example.com".
 @/textblock
 */

@property (readonly, retain) NSString *hostName;

/*!
 @property representedObject
 @abstract can be anything or nothing, for example an <tt>ABPerson</tt>.
 */

@property (retain) id representedObject;

/*!
 @property isValid
 @abstract YES if address is valid. Email validation.
 */

@property (readonly) BOOL isValid;

@end

/*!
 @class MessageAddressee
 @abstract Represents an email address.
 @discussion <tt>address</tt> is required.
 */

@interface MessageAddressee : NSObject <MessageAddressee, NSCopying, NSCoding> { 
@private;
	NSString *_address;
	NSString *_displayName;
	NSString *_userName;
	NSString *_domain;
	NSString *_hostName;
	NSString *_fullEmailAddress;
	
	id _representedObject;
}

/*!
 @method initWithDisplayName:address:
 @abstract Use to an initialize a new instance of <tt>MessageAddressee</tt>.
 @discussion If email is nil or an empty string this method returns nil.
 @param name
 The name used for display.
 @param emailAddress
 The email address.
 */

- (id)initWithDisplayName:(NSString *)name address:(NSString *)emailAddress;

/*!
 @method initWithString:
 @abstract Splits the name and the address of full email address and then calls @link initWithDisplayName:address: initWithDisplayName:address: @/link.
 @param string
 the full email address. @textblock e.g "John Doe <jdoe@example.com>". @/textblock
 */

- (id)initWithString:(NSString *)string;

@property (retain) NSString *displayName;
@property (retain) NSString *address; /* Cannot be nil */
@property (retain) NSString *userName;
@property (retain) NSString *domain;
@property (retain) NSString *hostName;
@property (readonly) NSString *fullEmailAddress;
@property (retain) id representedObject;
@property (readonly) BOOL isValid;

@end